~ chicken-core (master) /manual/Module (chicken load)

  1[[tags: manual]]
  2[[toc:]]
  3
  4== Module (chicken load)
  5
  6This module contains various procedures for loading code.  Note that
  7the main procedure for loading code, {{load}}, is part of
  8[[Module scheme]]; the {{chicken load}} module only contains
  9''extensions'' to the standard.
 10
 11=== A note on loading of shared extension libraries
 12
 13The functionality of loading shared objects into the runtime is only
 14available on platforms that support dynamic loading of compiled
 15code. Currently Linux, BSD, Solaris, Windows (with Cygwin) and HP/UX
 16are supported.  Loading source files works everywhere.
 17
 18=== load-relative
 19
 20<procedure>(load-relative FILE [ENVIRONMENT])</procedure>
 21
 22Similar to {{load}}, but loads {{FILE}} relative to the path
 23of the currently loaded file.
 24
 25=== load-noisily
 26
 27<procedure>(load-noisily FILE #!key ENVIRONMENT TIME PRINTER)</procedure>
 28
 29As {{load}} but the result(s) of each evaluated toplevel-expression
 30is written to standard output. If {{ENVIRONMENT}} is given and not {{#f}},
 31then each expression is evaluated using this environment. {{ENVIRONMENT}} may also be
 32a procedure used to evaluate each toplevel form. If {{TIME}} is given and not false, then
 33the execution time of each expression is shown (as with the {{time}} macro).
 34If {{PRINTER}} is given and not false, then each expression is
 35printed before evaluation by applying the expression to the value of this
 36argument, which should be a one-argument procedure.
 37
 38See also the [[#load-verbose|load-verbose]] parameter.
 39
 40=== load-library
 41
 42<procedure>(load-library UNIT [LIBRARYFILE])</procedure>
 43
 44On platforms that support dynamic loading, {{load-library}} loads
 45the compiled library unit {{UNIT}} (which should be a symbol). If the
 46string {{LIBRARYFILE}} is given, then the given shared library will
 47be loaded and the toplevel code of the specified unit will be executed.
 48If no {{LIBRARYFILE}} argument is given, then the libraries given in the
 49parameter {{dynamic-load-libraries}} are searched for the required unit.
 50If the unit is not found, an error is signaled.
 51
 52Note that {{LIBRARYFILE}} is considered relative to the {{dlopen(3)}}
 53search path by default. In order to use a file relative to the current
 54working directory, a relative or absolute pathname must be used, i.e.
 55{{LIBRARYFILE}} must contain at least one slash ({{"/"}}).
 56
 57=== require
 58
 59<procedure>(require ID ...)</procedure>
 60
 61If any of the named extension libraries {{ID}} are not already loaded
 62into the system, then {{require}} will look up the location of the
 63shared extension library and load it.  If {{ID}} names a library-unit
 64of the base system, then it is loaded via {{load-library}}. If no
 65extension library is available for the given ID, then an attempt is
 66made to load the file {{ID.so}} or {{ID.scm}} (in that order) from one
 67of the following locations:
 68
 69* the current directory
 70* the current repository path (see {{repository-path}})
 71
 72Each {{ID}} should be a symbol.
 73
 74
 75=== provide
 76
 77<procedure>(provide ID ...)</procedure>
 78
 79Registers the extension IDs {{ID ...}} as loaded. This is mainly
 80intended to provide aliases for certain library identifiers.
 81
 82
 83=== provided?
 84
 85procedure: (provided? ID ...)
 86
 87Returns {{#t}} if extension with the IDs {{ID ...}} are currently
 88loaded, or {{#f}} otherwise.
 89
 90
 91=== Tuning how code is loaded
 92
 93==== dynamic-load-libraries
 94
 95<parameter>(dynamic-load-libraries)</parameter>
 96
 97A list of strings containing shared libraries that should be checked
 98for explicitly loaded library units (this facility is not available on
 99all platforms). See {{load-library}}.
100
101
102==== load-verbose
103
104<parameter>(load-verbose)</parameter>
105
106A boolean indicating whether loading of source files, compiled code
107(if available) and compiled libraries should display a message.
108
109
110==== set-dynamic-load-mode!
111
112<procedure>(set-dynamic-load-mode! MODELIST)</procedure>
113
114On systems that support dynamic loading of compiled code via the
115{{dlopen(3)}} interface (for example Linux and Solaris), some options
116can be specified to fine-tune the behaviour of the dynamic
117linker. {{MODE}} should be a list of symbols (or a single symbol)
118taken from the following set:
119
120; {{local}} : If {{local}} is given, then any C/C++ symbols defined in the dynamically loaded file are not available for subsequently loaded files and libraries. Use this if you have linked foreign code into your dynamically loadable file and if you don't want to export them (for example because you want to load another file that defines the same symbols).
121; {{global}} : The default is {{global}}, which means all C/C++ symbols are available to code loaded at a later stage.
122; {{now}} : If {{now}} is specified, all symbols are resolved immediately.
123; {{lazy}} : Unresolved symbols are resolved as code from the file is executed. This is the default. 
124
125Note that this procedure does not control the way Scheme variables are handled -
126this facility is mainly of interest when accessing foreign code.
127
128
129---
130Previous: [[Module (chicken keyword)]]
131
132Next: [[Module (chicken locative)]]